The UniPalUI (UPI for short) is a blueprint focused SDK set-up for implementing UniPalUI integrations with your mod. If you're using Lua, you can use this documentation along with the Blueprints as a guide to set up your own integrations, though you'll need to use some blueprints to use UniPalUI to its full potential.


[- How To Install -]

Simply copy the "Mods" folder into the "Content" folder of your devkit / UE5 environment, then load up your usual project. (The assets are uncooked, so they import directly and can be accessed easily)


[- Usage Instructions -]

The SDK provides 'dummy' files/assets you point your mod to, then when you export your mod and load it in-game with UniPalUI installed, it will use those functions within UniPalUI as intended. DO NOT include the SDK files with your mod, this will break UniPalUI and the API, I've set up an asset label that should keep it separated, but double check the ChunkID to make sure it doesn't conflict with your mod if you use the packaging method!

When importing the SDK, do not change the file path/structure for the UniPalUI folder! The file path must match exactly in order for the API to work properly once you get in-game. Technically, if you don't wish to 'install' the SDK or have issues with the provided one, you can still create a 'dummy actor' in the appropriate folder and re-create the functions/events seen in teh SDK to still access the functions and use whatever you need (Check definitions below for names and variables). Similarly, if there are API functions you're not using you can remove them from your instance of the SDK if you ever find a reason to do so. (This can be useful if an update broke a certain function and the SDK hasn't been updated to fix it yet)


[- UniPalUI's Methodology -]

Understanding some basics about how UniPalUI is structured and how it functions will help you to quickly understand how the API is set up and how to use it, so here's a simplified explainer. This section isn't required to read, but I recommend it regardless.

The Main "UniPalUI" Actor is used to run all of the API and stores any data you may wish to access, this is what we'll reference when calling the API. It's a simple Actor with "Actor" as the parent class with all its logic being custom. UniPalUI is set up with 3 components, the Register, the Callback System, and the Functions Interface.

The Register is called to tell UniPalUI what objects we wish to register as individual mods as well as telling UniPalUI what inputs to listen for and what mods should receive different callbacks such as registering for a menu in the Mod Menu Selection. All mods that want to interact with the API need to first register themselves so UniPalUI knows which object should receive callbacks to run logic with.

The Callback System uses the data collected by the Register to know which objects should receive callbacks for different inputs/events and keep track of what's currently going on and being active. When you interact with UniPalUI, it will run logic which finds and sends a callback through the Functions Interface so the registered mod is able to respond with its own logic.

The Functions Interface is a Unreal Engine Interface called "UPI_InterfaceFunctions" which is how your mod object will listen for UniPalUI's callbacks to run your own logic. An interface is a type of blueprint that can be applied to any object/actor class which allows calling pre-set functions without needing to know the objects class or inheritence. This allows any object to be used as a callback handler, for instance UniPalUI uses the main Actor as its callback handler, but another mod I make uses an Actor Component, another uses a custom Object. You can decide which type is best for your use case, just remember to implement the Interface and set logic to the appropriate callbacks.


[- Usage Guide -]

Here's a quick and simple list of what you'll need to get started using UniPalUI.

First, determine what you'll use for your callback object. At first I recommend your main ModActor just to get started, then you can move to other methods if required. On this object in the "Class Settings" you'll use the "Implement Interface" option on the right panel by default to add the "UPI_InterfaceFunctions". This will give you the "interfaces" tab on the left side which now should show the UPI API functions after a quick compile. You can now double-click these to implement them and run any logic you wish when they are called.

These functions don't do anything on their own however, so now we need to register with UniPalUI so it knows what to listen for and what to call back for. We'll first use the "UPI_RegisterMod" API functions, this will allow us to input the object we implemented the Interface on so it can receive callbacks, as well as the name of the mod as well as the creator, and whether we should register a menu for the UI's Mod Menu Selection screen (When you enable RegisterMenu there will be an option with your mod's name added to UniPalUI's first screen, then when the player clicks that menu entry your mod will receive a callback to then run any menu logic).

If all you want is a mod menu for configuration or something, then all you need to do is make sure "RegisterMenu" is enabled and you're good to go! However, if you wish to register input as well (Keybinds) then you'll also want to run "RegisterInput" for each input you wish for UniPalUI to listen for and callback to your mod with. UniPalUI will try and prevent overlap, so make sure to check both the "Valid" and "Active" outputs to make sure your input is actually being used, otherwise you'll want to run some sort of handling code for that situation. With the input node you just need an InputName which you can use in other API functions to enable/disable/modify keybinds as well as the key you want (you can also register to report held inputs as well in the same node).

To use the callbacks now we just need to apply the logic to the Interface functions! For instance, for the Menu (if you had RegisterMenu enabled) when clicked in the Mod Selection Menu, will open up a new menu and callback to your mod using the "UPI_Callback_MenuOpened" Event with no menu name and waits for your logic to run. In your mod all you have to do is double click the "UPI_Callback_MenuOpened" from the interface mentioned before and implement it into your Event Graph on the object you registered for callbacks, then it will run that logic any time a menu associated with your mod is opened! You'll do this same thing for the inputs as well, though these are the callback_key events.

By default menus are empty, so this is where your logic comes in. UniPalUI as an api function called "UPI_AddMenuOption" which adds additional buttons to the currently active menu, so all you have to do is listen for the menu being openned, then call this function for every button you want to add! This will have a BoxType (listed below in the API descriptions), DisplayText, SettingText (only used by certain box types), as well as the Callback parameter. When that button is clicked it will then call the "UPI_Callback_UI" function with the currently open menu, the callback you entered for that button, the input given, as well as a reference to the menu box itself. Let's say this menu button is just a text entry that adds to a number at the end of it, for this we add the menu box with "UPI_AddMenuOption" and set the callback to something like "AddToNumber", then in our logic we'll check the callback and see if it equals "AddToNumber", if it does we can add to our internal tracker for that number (like, an integer variable in your mod) and then call the "UPI_UpdateMenuOpion" API function to then update the Display text. (Note : The Update function only update entries that are not left default, so if you only need to update the DisplayText for instance you only need to enter something for the DisplayText entry, use the "MenuBox" from the callback event and plug it into the "MenuBoxtoChange" entry, then leave everything else blank. You can also use this update function to change any other variable on the MenuBox itself)

And that's it! Now you have a working menu and can implement any logic you want! (It's probably easier to just look at the SDK example mod, but maybe someone will prefer the text verison, idk. >.<)



[- Menu Box Types -]

When registering a menu you'll have a Name variable "BoxType", this accepts very specific inputs to generate different types of menu boxes. The value is a Name instead of something like an enum so that you don't need to update the SDK for newer box types and keep compatibility, however it also makes it slightly more complicated to implement, here's the box types.

Menu BoxTypes
    Text
        Generates a menu box that displays text, can be hovered and selected, when selected it will trigger a callback with "Select" as the input return
    Toggle
        Generates a menu box with text and a toggle button, can be hovered and selected, when selected it will toggle the BoolState of the menu box and trigger a callback with "Select" as the input return, check the BoolState of the MenuBox reference to see what the user toggled the menu box to
    Select
        Generates a menu box that has the display text on the left of setting text on the right that has selection arrows on each side allowing left/right inputs, can be hovered and the arrows may be selected, when the left arrow is selected the callback will have "Left" as the input return, the right arrow will have "Right" as the input return
    Header
        Generates a menu box without any border and just DisplayText, has no callback features
    Custom
        Generates an empty box without any logic or contents, allows you to insert your own widget buttons for custom logic if desired while maintaining the menu box's variables and inserting directly into the menu (Note : Does not apply width adjustment logic in the current build of 0.1 DEV)
    
(Note : Some menu box types didn't make it into 0.1 DEV, this includes a slider, text input, dropdown, special page switch, and key switch type. These boxes will be implemented in later versions of UniPalUI and added to this list with proper docs when available. This is also why slider variables are available but not actively used since the slider box was not ready for proper usage yet)



~!!!!~ [- API Referneces / Explanation -] ~!!!!~

UniPalUI Actor Variables
Add PalPlayer [PalPlayerCharacter]
        The local pal player character for ease of access

Add PalPlayerController [PalPlayerController]
        The local pal player controller for ease of access

Add HideUI [Boolean]
        Whether UniPalUI should attempt to hide the game's UI (Be very careful messing with this value, hidding the UI in the wrong scenario can cause the player to soft-lock inbetween gameplay states!)

API Functions (UniPalUI Actor)
    UPI_RegisterMod
        Registers a mod with UniPalUI with what object implements the interface and should get callbacks, whether a menu should be registered, and some additional information.
            CallObject [Object]
                The Callback Object you wish to register for your mod, this object will receive the callbacks from UniPalUI and be used as a unique identifier for your mod (You'll input this callback object reference into all your calls to UniPalUI)
            ModName [String]
                A display name for your mod, this will show up in the menus and any user interface stuff UniPalUI generates to interact with your mod
            ModCreator [String]
                Displays in UniPalUI's generated UI elements for your mod, use this to show who created the mod
            RegisterMenu [Boolean]
                Whether an entry for your mod should be added to the Mod Menu Selection screen (Note : You can still manually open a menu using the UPI_OpenMenu function, it just won't show up in the mod selection screen)
            SecureCode [Name]
                Secure code used by the "UPI_SecureCode" interface function to help protect against malicious actors that may target your mod and change critical information. (Note : This feature can typically be ignored, it was a requested feature after community members received harassment from admins in the Palworld Modding Discord and threats that they would sabotage mods. Use this functionality to help protect against these attacks which may try to alter your mod's details through UniPalUI as a proxy attack vector)
            Returns : Valid [Boolean]
                Whether the registeration was successful
            Returns : ErrorOutput [Name]
                Simple error return if the registeration was unsuccessful to inform you about what may have gone wrong

    UPI_RegisterInput
        Registers an Input for UniPalUI to listen for and callback to your mod for. Input is implemented in a way to where overlapping keybinds is not allowed so make sure to listen for the return variables of Valid and Active to ensure your input is running as well as set-up a handler for if they are not. Modifier keys such as Shift, Ctrl, Alt can't be registered as the main key. (Tip : You can call UPI_RegisterInput with the same InputName to update the keybinding and its details at any time)
            CallObject [Object]
                The callback object for your mod
            InputName [Name]
                A unique 'internal' name used to identify this specific input, this value is returned with the input callback as well as used to activate/deactivate/modify this input (Note : Once an input is registered it can't be un-registered, instead you should use the UPI_SetInputActive function call to set whether you want callbacks to your input or not)
            InputDesc [String]
                Quick display which shows next to your input in UniPalUI, use this to quickly describe what the input does (for instance, if the input summons rocks entering "Summon Rocks" as the desc makes sense, if there is no InputDesc entered then the InputName is used as a fallback)
            InputActive [Boolean]
                Whether the input should start out active or not (Inputs will only send callbacks if they are Active, but only one mod can have the same keybind active at a time)
            InputKey [Key]
                Which key, using Unreal Engine's Key type, to listen/register for (callbacks will be received if this key and any modifiers enabled are pressed/held/ect)
            Shift [Boolean]
                Whether the Shift modifier key needs to be held for this input
            Control [Boolean]
                Whether the Ctrl/Control modifier key needs to be held for this input
            Alt [Boolean]
                Whether the Alt/Alternate modifier key needs to be held for this input
            InputState [Name]
                Which input state this keybind is for (Callbacks will only be sent if the InputState matches the current state, use UPI_EnterInputState and UPI_ExitInputState to manage input states, multiple mods can register the same input if they have different input states, input states should only be used if there is a definite state swich where you'll only be using that state for a limited time such as maybe pressing a key to enter a selection mode with your own keybinds which you'll then immediately want to exit out of that state when you are finished, failing to exit your InputState properly will cause things to break or lock up the input/menu system)
            ReportHold [Boolean]
                Whether to report when the input is held down or not (you can also handle this yourself by using both the UPI_Callback_KeyPressed and UPI_Callback_KeyReleased callbacks)
            TillHold [Float]
                How long, in seconds, until the first held callback should be called (set to 0.0 for the first frame after being pressed, though this isn't recommended, instead use something like 0.3 as a baseline)
            HoldInterval [Float]
                How often the hold callback should be called after the first callback is made (think of this how quickly the input should repeat after it starts, use TillHold to create a longer delay then set HoldInterval to a lower delay to create a delayed hold input with faster repeats)
            Returns : Valid [Boolean]
                Whether the register was successful or not
            Returns : Active [Boolean]
                Whether the input was registered as active or not (If you tried to register your input as active but another mod already registered the key, then your key will register but as Inactive, you can call this function again with the same InputName and different keys to automatically switch to another keybind for your input)
            Returns : ErrorOutput [Name]
                A simple error return message to help understand what may have gone wrong with your registeration
    
    UPI_SetInputActive
        Sets an input as either active or inactive, use this to manage when you want to listen for certain inputs (Generally you should only listen for inputs you actively want or need to listen for, for instance if I have an input that is only valid while in a certain state you should make those inputs inactive until you switch into that state, deactivating them again when leaving that state, UniPalUI may try to do this on its own but it plays it extremely safe as to not break intended behavior of other mods so it's always best practice to do it yourself)
            CallObject [Object]
                The callback object for your mod
            InputName [Name]
                The InputName variable for the input you wish to make active/inactive
            InputActive [Boolean]
                Whether the input should be set as active or Inactive
            Returns : Valid [Boolean]
                Whether the switch was successful or not
            Returns : ErrorOutput [Name]
                Simple error return if the switch was unsuccessful

    UPI_EnterInputState
        Enters an input state, when inside an input state only the inputs registered for the current input state are handled (only use this feature when it makes absoulte sense, remember to use UPI_ExitInputState when you're done with the current input state so other inputs return to a functioning state)
            CallObject [Object]
                The callback object for your mod
            EnterInputState [Name]
                The input state to enter (the same input state is only valid a single time, if you enter an input state, then input state changes, then enter the same input state again it will be moved to the top of the stack, if you exit a state while it is not on top of the stack it will still remove its single instance)
            Returns : Valid [Boolean]
                Whether the input state was successfully entered
            Returns : ErrorOutput [Name]
                A simple error return message if entering the input state was not successful

    UPI_ExitInputState
        Exits an input state regardless of where it is in the stack (should always be called after a mod is done with a given input state)
            CallObject [Object]
                The callback object for your mod
            ExitInputState [Name]
                The input state to exit/remove from the stack
            Returns : Valid [Boolean]
                Whether the input state was found and removed from the stack
            Returns : ErrorOutput [Name]
                A simple error return message if removing the input state was not successful

    UPI_SendNotif
        Sends a message to the notification UI (useful for either quick gameplay information for the player or on-screen debug information)
            CallObject [Object]
                The callback object for your mod
            Message [Text]
                The message to display in the notification

    UPI_OpenMenu
        Opens a UniPalUI menu instance for your mod, if the menu is not already open it will open in a standalone instance without the Mod Menu Selection, can be used in menus to switch pages (The input state will automatically enter the menu's specific input state wehn entering a standalone instance)
            CallObject [Object]
                The callback object for your mod
            Menu [Name]
                The callback 'menu' variable for the menu to open
            MenuTitle [String]
                Display title to show at the top of the menu under the mod name (leave blank to omit any menu title)
            Returns : Valid [Boolean]
                Whether opening the menu was successful
            Returns : ErrorOutput [Name]
                A simple error message if the opening the menu was not successful

    UPI_CloseMenu
        Attempts to exit the current menu (This will only be successful if a menu with your callback object assigned is currently active)
            CallObject [Object]
                The callback object for your mod
            Returns : Valid [Boolean]
                Whether a menu was successfully closed or not
            Returns : ErrorOutput [Name]
                A simple error return if a menu was not successfully closed

    UPI_AddMenuOption
        Adds a UI button with the assigned type to the currently open menu and sets the callback for said menu to the given callback object, all variables can be set regardless of the BoxType but only certain values will display to the user depending on said BoxType
            CallObject [Object]
                The callback object for your mod
            BoxType [Name]
                The type of menu box to generate (check "Menu Box Types" for more information, if not type is set or is invalid then the box won't be created)
            BoxID [Name]
                An optional ID to give the menu box, purely for your own use, UniPalUI doesn't use this value in any way
            DisplayText [Text]
                Sets the text to show in the in the "DisplayText" section of the menu box, this can change depending on the BoxType
            SettingText [Text]
                Sets the text to show in the "SettingText" section of the menu box, not all BoxTypes have a SettingText field
            Callback [Name]
                The callback variable you wish to give this menu box, will be replicated in the callback when the user interacts with this menu box
            BoolState [Boolean]
                Whether the current menu box is set to True or not, only used for "Toggle" type menu boxes
            SliderState [Float]
                Current slider value of the menu box
            SliderMin [Float]
                Current minimum slider value of the menu box
            SliderMax [Float]
                Current maximum slider value of the menu box
            Returns : Valid [Boolean]
                Whether the menu box was successfully created
            Returns : ErrorOutput [Name]
                A simple error return if the menu box was not successfully created
            Returns : Index [Integer]
                The current menu index for the generated menu box (New menu boxes are always put to the end of the stack, you can use this or the MenuBox return to update/modify the generated menu box after it has been created)
            Returns : MenuBox [UPI_MenuGenBox]
                Returns a reference to the menu box widget for further logic if required (You can also use this reference to change the menu box and its elements as you see fit, or store it in a data map for your own menu box tracking instead of using the Index value, menu boxes should only be considered valid while in the same menu even if the reference may remain valid after the menu closes do-to cache systems)

    UPI_UpdateMenuOption
        Updates a menu box with new data, any fields left blank will change (including BoxType) while anything with a non-default value will update and change, certain values, because of how they work, will try and trigger a change if not specifically set
            CallObject [Object]
                The callback object for your mod
            IndexToChange [Integer]
                Index of the menu box to change, set to -1 to use the MenuBoxToChange instead
            MenuBoxToChange [UPI_MenuGenBox]
                Which menu box to change using the menu box reference
            NewBoxType [Name]
                New BoxType to change to
            NewBoxID [Name]
                New BoxID to change to
            NewDisplaytext [Text]
                New DisplayText to implement, clears old DisplayText
            NewSettingText [Text]
                New SettingText to implement, clears old SettingText
            NewCallback [Name]
                New callback variable to give this menu box
            NewBoolState [Boolean]
                New boolstate to set, use BoolState on the menu box reference to keep this unchanged
            NewSliderState [Float]
                New slider state to set, set to -1.0 to keep this unchanged
            NewSliderMin [Float]
                New minimum slider value to set, set to -1.0 to keep this unchanged
            NewSliderMax [Float]
                New maximum slider value to set, set to -1.0 to keep this unchanged
            Returns : Valid [Boolean]
                Whether the update was successful
            Returns : ErrorOutput [Name]
                A simple error message if the update was not successful

    UPI_UpdateDescBox
        Sets the discription box to appear and sets the text it should display, the discription box will reset every time a new menu box is hovered or a menu changes
            CallObject [Object]
                The callback object for your mod
            DescTitle [Text]
                The text which should appear in the description box' title segment
            DescText [Text]
                The text which should appear in the description box' text field below the title
            Returns : Valid [Boolean]
                Whether updating the description box was successful
            Returns : ErrorOutput [Name]
                A simple error message if the update was not successful

    UPI_ResetMenu
        Resets the current menu by clearing all boxes and performing a callback as if it was just opened without adding another instance to the menu stack (useful if you need to re-calculate all entries in the menu list or the menu structure needs to completely change)
            CallObject [Object]
                The callback object for your mod
            Returns : Valid [Boolean]
                Whether the reset was performed
            Returns : ErrorOutput [Name]
                A simple error message if the reset did not occur

    UPI_ExitMenu
        Exits any active UniPalUI menu (Useful if you've opened a standalone menu but have an event which would end the interaction without user input)
            Returns : Valid [Boolean]
                Whether the menu was closed

Callback Events (UPI_InterfaceFunctions)
    UPI_Callback_KeyPressed
        Calls when a registered input for the callback object is pressed
            InputState [Name]
                The current input state when the input was pressed
            InputName [Name]
                The name given to the input that was pressed
            Key [Key]
                The Unreal Engine Key struct return for the pressed input
            Shift [Boolean]
                Whether the Shift key was being held with the input
            Control [Boolean]
                Whether the Ctrl/Control key was being held with the input
            Alt [Boolean]
                Whether the Alt/Alternate key was being held with the input

    UPI_Callback_KeyHold
        Calls when a registered input is held for the appropriate amount of time based on the TillHold/HoldInterval variables
            InputState [Name]
                The current input state when the input was held
            InputName [Name]
                The name given to the input that was held
            Key [Key]
                The Unreal Engine Key struct return for the held input
            Shift [Boolean]
                Whether the Shift key was being held with the input
            Control [Boolean]
                Whether the Ctrl/Control key was being held with the input
            Alt [Boolean]
                Whether the Alt/Alternate key was being held with the input

    UPI_Callback_KeyReleased
        Calls when a registered input is released, release is also triggered if any required key is lifted
            InputState [Name]
                The current input state when the input was released
            InputName [Name]
                The name given to the input that was released
            Key [Key]
                The Unreal Engine Key struct return for the released input
            Shift [Boolean]
                Whether the Shift key was being held with the input
            Control [Boolean]
                Whether the Ctrl/Control key was being held with the input
            Alt [Boolean]
                Whether the Alt/Alternate key was being held with the input

    UPI_Callback_MenuOpened
        Calls when the callback object opens a menu, use this function to create your menu box'
            Menu [Name]
                Menu value that was opened
            FromMenu [Name]
                Menu that was open previously, not always valid
            FromSameMod [Boolean]
                Whether the menu is translating from a menu with the same callback object

    UPI_Callback_UIHover
        Calls when a generated menu box is hovered
            Menu [Name]
                The currently active menu
            Callback [Name]
                The callback value of the menu box that was hovered
            Index [Integer]
                The current index of the menu box that was hovered
            MenuBox [UPI_MenuGenBox]
                The menu box reference that was hovered

    UPI_Callback_UI
        Calls when a generated menu box is activated (an input is provided)
            Menu [Name]
                The currently active menu
            Callback [Name]
                The callback value of the menu box that was activated
            Input [Name]
                The input that was passed to the menu box (Select/Left/Right, only relevant for certain BoxTypes)
            Index [Integer]
                The current index of the menu box that was hovered
            MenuBox [UPI_MenuGenBox]
                The menu box reference that was hovered

    UPI_Callback_MenuClosed
        Calls when the callback object's menu is closed either through calling a close function or because the user closed the menu
            Menu [Name]
                Menu value that was closed
            ToMenu [Name]
                The new menu being transitioned to, not always valid
            FromSameMod [Boolean]
                Whether the menu is translating to a menu with the same callback object


Callback Functions (UPI_InterfaceFunctions)
    UPI_SecureCode
        Used to help secure valuable data in a menu register and prevent vandelism from malicious actors such as the admins of the paworld modding discord, typically not needed unless you are being actively targetted by another modder
            PassedCode [Name]
                The passcode sent from an API call
            Return : EnterCode [Name]
                Passcode response


Menu Box Varibles [UPI_MenuGenBox]
    BoxID [Name]
        The current BoxID value for the menu box (use with any callback)
    DisplayText [Text]
        Current DisplayText for the menu box
    SettingText [Text]
        Current DisplayText for the menu box
    Callback [name]
        Current callback for the menu box (use with any callback)
    BoolState [Boolean]
        Current boolean state of the menu box (use with the toggle box callback)
    SliderState [Float]
        Current slider state for the menu box
    SliderMin [Float]
        Current minimum slider value for the menu box
    SliderMax [Float]
        Current maximum slider value for the menu box